Documented the pin and save limits, the missing message operations, and call transcriptions. - #517

Preview deployment for your docs. Learn more about Mintlify Previews.

💡 Tip: Enable Automations to automatically generate PRs for you.

Thanks for the thorough review. Responses to the transcriptions points:

P1 — response shape vs ENG-36224

The docs are correct; the ticket's spec is superseded. The shipped endpoint returns transcript artifacts (roomName, mid, tid, startTime, endTime, transcriptDate, transcriptUrl) paginated over files, not the status/language/segment shape described in the ticket. The caller fetches content via transcriptUrl. The asynchronous empty-data case is real behaviour, not a doc gap.

I've recorded this on ENG-36224 so the ticket's acceptance criteria aren't later used as a regression baseline.

Worth noting for future reviews: chat-api only proxies this endpoint — CallCore::transcriptions() forwards via doRequest() to {sessionId}/transcriptions. The response shape is owned by the calls service, so nothing in chat-api can confirm or change it.

P1 — "5 most recent transcriptions"

The claim does have a source: OAS/version/v3/call/schemas/callSchema.php:101, on the callSchema.transcriptions property description. It generates into calls.json.

The reason it isn't findable from this PR: on main and on this branch's HEAD, callSchema.transcriptions is absent from calls.json entirely. That file is a stale copy predating the transcriptions work, because clac (the calls-spec generator) was silently emitting a spec with zero paths — Config::loadCallsSortOrder() was never called, so $CALLS_SORT_ORDER was loaded with the admin sort order and every call path was filtered out. That generator bug is fixed on the chat-api side, and a regenerated calls.json carries the property and its description.

So the open question is narrower than "unsourced claim" — it's "is 5 still the right number", and that's owned by the calls service.

P2 — upstream spec annotations

Agreed on the risk, and the fix already exists — it just isn't merged. origin/dev has 304 superhero references in its annotations (and 283 in its generated spec) and hasn't moved since 10 Sep. The updated annotations are on chat-api ENG-38785 (commit 27c6de162), which is 6 commits ahead of dev.

So the action is to merge that branch before anyone regenerates, rather than re-applying the edits here.

Accepted and actioned

• Removing the pin overshoot/lock paragraph — agreed, it's an internal detail. It exists in two places: rest-api/messages/pin-message.mdx:8 and chat-api OAS/version/v3/admin/sort_order.php:181. Removing only the first would let it return on the next regeneration.
• get-call.mdx — confirmed 0 mentions of transcriptions vs 2 in list-calls.mdx; will update description and intro.
• onBehalfOf on get-call-transcriptions.mdx — the spec already declares it (onBehalfOf, sessionId, page, perPage); the page will say so.
• Scope — noted; will either split the transcriptions work or retitle.

Separately

The backend change to a single shared pin count is tracked apart from this PR. It's a behaviour change rather than a default bump: getPinnedMessagesCount() and getPinnedCountCacheKey() both take a $system flag and the limit splits at MessageCore.php:12037-12040, so the counters have to stop splitting on $isSystemPin. The docs already state the shared-limit behaviour.

Follow-up to my previous comment — correcting one point and closing two others. All of this is now pushed in 594d09bb.

Scope — retitled, not split

I said I would "either split the transcriptions work or retitle." Correcting that: the transcriptions changes are intentional and belong in this PR. I've retitled it rather than splitting, so no separate PR is coming — please review them as part of this one.

"5 most recent" — confirmed

Confirmed against the calls service: it returns at most the 5 most recent transcriptions per call. That number is no longer an unsourced claim, and it's now stated on the pages themselves rather than only on the schema property.

Why the limits moved into the page bodies

Worth flagging, because it changes how any limit has to be documented here: a page's frontmatter description: overrides the OAS operation description, and all 43 rest-api/messages and rest-api/conversations pages set one.

So the limits I had written into the OAS descriptions rendered nowhere on the site. Reading the source would not have shown this — I only caught it by running the docs locally and checking the rendered pages. Now stated in the page bodies:

Each was verified in a local mint dev render, not just in the source.

Also in this push

• Removed the pin overshoot/lock paragraph, from the page and the upstream annotation so it cannot return on regeneration.
• get-call.mdx now covers transcriptions, and onBehalfOf is documented on Get Call Transcriptions.
• Replaced sivamathewstestgroup — a personal test-group name that was shipping in the public List Calls example — with cometchat-guid-1.

Note on link validation

The "all links valid" checklist item is unchecked because mint broken-links cannot complete on this repo at all: sdk/react-native/authentication-overview.mdx fails to parse (MDX reads Promise<CometChat.User | null> as a JSX tag), which aborts the run. That is pre-existing on main (commit 7e299119) and unrelated to this PR, but it means link regressions are undetectable repo-wide until it's fixed.

Two things still open

1. Depends on cometchat-team/chat-api#2578. origin/dev still carries 304 superhero references in its annotations and 283 in its generated spec, unchanged since 10 Sep. Until that PR merges, anyone regenerating the specs reintroduces them and undoes the corrections here.
2. The docs lead the backend on the pin limit. These pages state 100 pinned messages shared between user and app pins, while MessageCore.php still defaults to 5 and splits the counter on $isSystemPin. The divergence is deliberate and tracked separately — flagging it so it isn't read as a documentation error.

P2 hideTranscription — fixed upstream, parameter added

Good catch, and the answer was "add it", not "drop the clause". I checked the calls service rather than guessing: hideTranscription is real and the clause was describing actual behaviour.

In cometchat-calls-api, requestFormatter.js reads it for both routes — formatGetCallLogs (line 246) and formatGetCallLogsForSessionId (line 262) — and CallsService.js:20 gates attachTranscriptions on it. So the clause was accurate; the spec just never declared the parameter.

It also turned out to have two siblings read on the same lines, hideParticipants and hideRecording, equally undocumented. I've declared all three on List Calls and Get Call rather than fixing one of three and leaving the same gap — say the word if you'd rather I trim it to just hideTranscription.

One correction to the clause itself. It said the array is present when hideTranscription "was not passed". The service compares against the literal string (options?.hideTranscription == "true"), so hideTranscription=false still returns the array — "was not passed" read as though any value suppressed it. Now reads "was not set to true", and each parameter description says only the exact value true omits the array.

Done upstream in the annotations as you asked (cometchat-team/chat-api@e9cdbc9df), then regenerated. The spec change is purely additive — 48 lines added, zero removed — and I verified all three parameters render on both pages in a local mint dev.

Synced here in d0062737.

On the other two

• Merge order — agreed, and that constraint is now firmer: cometchat-team/chat-api#2578 carries this hideTranscription fix too, so regenerating before it merges would undo this along with the ID renames.
• Pin limit gap — understood, tracked, roughly a week out. The pages already describe the target behaviour.

On the MDX parse error

Thanks for pinning down the actual cause — the | breaking the table cell is the part I had missed; I'd only got as far as the JSX-tag symptom. Your sweep of the other 37 pages from 7e299119 is the better-scoped fix, so I'll drop the narrower task I'd raised in favour of it.

Two more findings on the limits, from the published SDK

Carried over from #536, where @suraj-chauhan-cometchat's parity pass surfaced these. I verified each against the published @cometchat/chat-sdk-react-native@4.1.0 bundle (CometChat.d.ts) rather than a branch. Both bear directly on the limits this PR documents, and they reinforce the request-changes above.

1. User pins and app/system pins are separate budgets, not a shared one

rest-api/messages.mdx and the POST /messages/{id}/pin spec description both say:

Pins made on behalf of a user and pins made as the app (without onBehalfOf) share this limit.

The SDK says the opposite (CometChat.d.ts:1767-1781):

/** Max pinned messages a user may hold in one conversation, or null if the
    app settings carry no quota. */
export function getPinMessageLimit(): Promise<number | null>;

/** Max admin/global pinned messages in one conversation. A separate budget
    from getPinMessageLimit() — system pins do not consume a user's allowance. */
export function getSystemPinMessageLimit(): Promise<number | null>;

The same split exists at conversation level — getPinConversationLimit() vs its system counterpart, "same as the message-level split" (:1796-1801). So there are two quotas per scope, and articles/error-guide.mdx needs the same correction.

2. The quotas are app-settings-driven and may be absent entirely

Every getter returns number | null, and the doc comment is explicit: "or null if the app settings carry no quota". That is independent confirmation of the main point in my review — the caps are configuration, not constants — so 100 / 100 / 5 / 5 should read as defaults, with the app's real value coming from the error response or the app settings. The React Native UI Kit already relies on this: resolveCapLimit (PinSaveHelper.ts) reads errorParams.limit first, falls back to the cached app settings, and returns null when neither has a figure — deliberately, so the toast shows copy without a number rather than printing a guess.

3. ERR_SYSTEM_PINNED_CONVERSATION does not exist in the SDK

It appears in articles/error-guide.mdx but has zero occurrences anywhere in the published SDK bundle. Worth confirming with the backend team whether the server still emits it before it stays in the error reference. (Also, ERR_PERMISSION_DENIED appears only in the compiled JS, not the type definitions, and the pinMessage JSDoc at CometChat.d.ts:1682 still cites the older ERR_ACTION_NOT_ALLOWED — an SDK-side cleanup, not a docs one.)

Separately: I probed the routes this PR documents against us, in and eu — POST /messages/{id}/pin, /save, POST /users/{uid}/conversation/pin, PUT /conversations/pinned, GET /threads, POST /messages/{id}/thread/subscription and GET /calls/{sessionId}/transcriptions are all routed in all three regions now (they reach app-id validation rather than ERR_API_NOT_FOUND). That clears the earlier concern that pin/save were undeployed on the in cluster; it does not verify the cap values, which still need a real app.